<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.10"/>
<title>usbps: Main Page</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="HTML_custom.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="xlogo_bg.gif"/></td>
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">usbps
   </div>
   <div id="projectbrief">Xilinx SDK Drivers API Documentation</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.10 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li class="current"><a href="index.html"><span>Overview</span></a></li>
      <li><a href="annotated.html"><span>Data&#160;Structures</span></a></li>
      <li><a href="globals.html"><span>APIs</span></a></li>
      <li><a href="files.html"><span>File&#160;List</span></a></li>
    </ul>
  </div>
</div><!-- top -->
<div class="header">
  <div class="headertitle">
<div class="title">usbps Documentation</div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>This file contains the implementation of the <a class="el" href="struct_x_usb_ps.html" title="The XUsbPs driver instance data. ">XUsbPs</a> driver. It is the driver for an USB controller in DEVICE or HOST mode.</p>
<h2>Introduction</h2>
<p>The Spartan-3AF Embedded Peripheral Block contains a USB controller for communication with serial peripherals or hosts. The USB controller supports Host, Device and On the Go (OTG) applications.</p>
<h2>USB Controller Features</h2>
<ul>
<li>Supports Low Speed USB 1.1 (1.5Mbps), Full Speed USB 1.1 (12Mbps), and High Speed USB 2.0 (480Mbps) data speeds</li>
<li>Supports Device, Host and OTG operational modes</li>
<li>ULPI transceiver interface for USB 2.0 operation</li>
<li>Integrated USB Full and Low speed serial transceiver interfaces for lowest cost connections</li>
</ul>
<h2>Initialization &amp; Configuration</h2>
<p>The configuration of the USB driver happens in multiple stages:</p>
<ul>
<li>(a) Configuration of the basic parameters: In this stage the basic parameters for the driver are configured, including the base address and the controller ID.</li>
<li>(b) Configuration of the DEVICE endpoints (if applicable): If DEVICE mode is desired, the endpoints of the controller need to be configured using the <a class="el" href="struct_x_usb_ps___device_config.html" title="The XUsbPs_DeviceConfig structure contains the configuration information to configure the USB control...">XUsbPs_DeviceConfig</a> data structure. Once the endpoint configuration is set up in the data structure, The user then needs to allocate the required amount of DMAable memory and finalize the configuration of the <a class="el" href="struct_x_usb_ps___device_config.html" title="The XUsbPs_DeviceConfig structure contains the configuration information to configure the USB control...">XUsbPs_DeviceConfig</a> data structure, e.g. setting the DMAMemVirt and DMAMemPhys members.</li>
<li>(c) Configuration of the DEVICE modes: In the second stage the parameters for DEVICE are configured. The caller only needs to configure the modes that are actually used. Configuration is done with the: <a class="el" href="group__usbps__v2__2.html#ga6daace32113a806a6822a6d5943a93f4" title="This function configures the DEVICE side of the controller. ">XUsbPs_ConfigureDevice()</a> Configuration parameters are defined and passed into these functions using the: <a class="el" href="struct_x_usb_ps___device_config.html" title="The XUsbPs_DeviceConfig structure contains the configuration information to configure the USB control...">XUsbPs_DeviceConfig</a> data structures.</li>
</ul>
<h2>USB Device Endpoints</h2>
<p>The USB core supports up to 4 endpoints. Each endpoint has two directions, an OUT (RX) and an IN (TX) direction. Note that the direction is viewed from the host's perspective. Endpoint 0 defaults to be the control endpoint and does not need to be set up. Other endpoints need to be configured and set up depending on the application. Only endpoints that are actuelly used by the application need to be initialized. See the example code (xusbps_intr_example.c) for more information.</p>
<h2>Interrupt Handling</h2>
<p>The USB core uses one interrupt line to report interrupts to the CPU. Interrupts are handled by the driver's interrupt handler function <a class="el" href="group__usbps__v2__2.html#ga60e2b0f6fabc24cdf785d704ab2585d1" title="This function is the first-level interrupt handler for the USB core. ">XUsbPs_IntrHandler()</a>. It has to be registered with the OS's interrupt subsystem. The driver's interrupt handler divides incoming interrupts into two categories:</p>
<ul>
<li>General device interrupts</li>
<li>Endopint related interrupts</li>
</ul>
<p>The user (typically the adapter layer) can register general interrupt handler fucntions and endpoint specific interrupt handler functions with the driver to receive those interrupts by calling the <a class="el" href="group__usbps__v2__2.html#ga521c050d3b146bb58862f5fadf7f6ba6" title="This function registers the user callback handler for controller (non-endpoint) interrupts. ">XUsbPs_IntrSetHandler()</a> and <a class="el" href="group__usbps__v2__2.html#ga04fb0b564bcd01cdf33e29ca2732656a" title="This function sets the handler for endpoint events. ">XUsbPs_EpSetHandler()</a> functions respectively. Calling these functions with a NULL pointer as the argument for the function pointer will "clear" the handler function.</p>
<p>The user can register one handler function for the generic interrupts and two handler functions for each endpoint, one for the RX (OUT) and one for the TX (IN) direction. For some applications it may be useful to register a single endpoint handler function for muliple endpoints/directions.</p>
<p>When a callback function is called by the driver, parameters identifying the type of the interrupt will be passed into the handler functions. For general interrupts the interrupt mask will be passed into the handler function. For endpoint interrupts the parameters include the number of the endpoint, the direction (OUT/IN) and the type of the interrupt.</p>
<h2>Data buffer handling</h2>
<p>Data buffers are sent to and received from endpoint using the <a class="el" href="group__usbps__v2__2.html#ga6bfe53ec45a998d5673b80e11ab4d292" title="This function sends a given data buffer. ">XUsbPs_EpBufferSend()</a>, <a class="el" href="group__usbps__v2__2.html#ga1e4c0735be24ea24b73404db8d18133e" title="This function sends a given data buffer and also zero length packet if the Bufferlen is in multiples ...">XUsbPs_EpBufferSendWithZLT()</a> and <a class="el" href="group__usbps__v2__2.html#gac27a9d64ddf33a2400d7493e301a7192" title="This function receives a data buffer from the endpoint of the given endpoint number. ">XUsbPs_EpBufferReceive()</a> functions.</p>
<p>User data buffer size is limited to 16 Kbytes. If the user wants to send a data buffer that is bigger than this limit it needs to break down the data buffer into multiple fragments and send the fragments individually.</p>
<p>From the controller perspective Data buffers can be aligned at any boundary. if the buffers are from cache region then the buffer and buffer size should be aligned to cache line aligned</p>
<h3>Zero copy</h3>
<p>The driver uses a zero copy mechanism which imposes certain restrictions to the way the user can handle the data buffers.</p>
<p>One restriction is that the user needs to release a buffer after it is done processing the data in the buffer.</p>
<p>Similarly, when the user sends a data buffer it MUST not re-use the buffer until it is notified by the driver that the buffer has been transmitted. The driver will notify the user via the registered endpoint interrupt handling function by sending a XUSBPS_EP_EVENT_DATA_TX event.</p>
<h2>DMA</h2>
<p>The driver uses DMA internally to move data from/to memory. This behaviour is transparent to the user. Keeping the DMA handling hidden from the user has the advantage that the same API can be used with USB cores that do not support DMA.</p>
<pre>
 MODIFICATION HISTORY:</pre><pre> Ver   Who  Date     Changes
 ----- ---- -------- ----------------------------------------------------------
 1.00a wgr  10/10/10 First release
 1.02a wgr  05/16/12 Removed comments as they are showing up in SDK
		       Tabs for CR 657898
 1.03a nm   09/21/12 Fixed CR#678977. Added proper sequence for setup packet
                    handling.
 1.04a nm   10/23/12 Fixed CR# 679106.
	      11/02/12 Fixed CR# 683931. Mult bits are set properly in dQH.
 2.00a kpc 04/03/14 Fixed CR#777763. Corrected the setup tripwire macro val.
 2.1   kpc 04/28/14 Removed unused function prototypes
 2.2   kpc 08/23/14 Exported XUsbPs_DeviceReset API as global for calling in
                    code coverage tests.
 </pre> </div></div><!-- contents -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Copyright &copy; 2015 Xilinx Inc. All rights reserved.</li>
  </ul>
</div>
</body>
</html>
